Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

A94 Amber Docs generator #62

Merged
merged 14 commits into from
Jul 19, 2024
Merged

A94 Amber Docs generator #62

merged 14 commits into from
Jul 19, 2024

Conversation

Ph0enixKM
Copy link
Member

@Ph0enixKM Ph0enixKM commented Jan 31, 2024

Create a way to generate documentation. The implementation should:

  • Generate each markdown file for each module that is part of the project
  • Collect freestanding comment docs as documentation body
  • Aggregate comment docs that are directly above function declarations as the function documentation
  • Get the function signature and render it in the docs
  • Do not iterate through the external files
  • Error when no input specified
  • Accept output directory (defaults to docs/)

@Ph0enixKM Ph0enixKM linked an issue May 25, 2024 that may be closed by this pull request
5 tasks
@Ph0enixKM Ph0enixKM self-assigned this Jun 5, 2024
@Mte90
Copy link
Member

Mte90 commented Jun 25, 2024

Looking at the code there are too many conflicts maybe because it is changed a lot in the meantime?

I was looking to https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html and #237

@Mte90
Copy link
Member

Mte90 commented Jul 9, 2024

This PR can get the maximum priority?
So we can start working on the documentation?

@Mte90 Mte90 added this to the Amber 0.4.0-alpha milestone Jul 9, 2024
@Ph0enixKM
Copy link
Member Author

@Mte90 Now that the major bugs that had to be fixed by me are now gone - I will focus on this task

test2.md Outdated Show resolved Hide resolved
@Mte90
Copy link
Member

Mte90 commented Jul 18, 2024

Can be approved? @Ph0enixKM

@Ph0enixKM
Copy link
Member Author

@Mte90 I gave myself more time to think this through if this is the format that should be generated. Have you tested it?

amber --docs test.ab

The above instruction will generate test.md file with the documentation. It works that for each file that it includes it generates appropriate file in the same directory a new markdown file. I'm still thinking if this is the best way to do it. Probably creating a separate directory docs/ with all the files would be a better approach. And also I'm thinking that this should check whether we are importing files from the same root directory or not. If we import some third party library, then this shouldn't generate documentation for it.

@Ph0enixKM Ph0enixKM marked this pull request as draft July 18, 2024 11:24
@Ph0enixKM
Copy link
Member Author

I want to convert it to draft since I think I have to fix the issue I described before. I've added the appropriate code to the contributing guide

@Mte90
Copy link
Member

Mte90 commented Jul 18, 2024

I approve the idea of a dedicated docs folder, so we can see later how to implement that in the website repo.

@Ph0enixKM
Copy link
Member Author

Here is a piece of the documentation generated by the generator:

This is a documentation
That involves many interesting things

test

fun test(a: Text): Null 

This function is a test function
Here is an example:

test("Hello, World!")

foo

fun foo(a: [Num] = [1, 2, 3]): [Num] 

This also is a pretty interesting function

@Ph0enixKM
Copy link
Member Author

@Mte90 This PR is ready

@Ph0enixKM Ph0enixKM marked this pull request as ready for review July 18, 2024 16:07
Copy link
Member

@KrosFire KrosFire left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks pretty good to me

src/cli/cli_interface.rs Outdated Show resolved Hide resolved
src/cli/cli_interface.rs Outdated Show resolved Hide resolved
src/cli/cli_interface.rs Outdated Show resolved Hide resolved
src/compiler.rs Outdated Show resolved Hide resolved
@Ph0enixKM
Copy link
Member Author

@KrosFire can you actually approve this PR so that we can merge?

@Ph0enixKM Ph0enixKM merged commit d49c97a into master Jul 19, 2024
2 checks passed
@Ph0enixKM Ph0enixKM deleted the A94 branch July 19, 2024 09:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[Feature] Amber Docs generator
3 participants